home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / network / mail / pathalia.zoo / src / pathalia.man < prev    next >
Text File  |  1991-01-12  |  9KB  |  235 lines
  1. PATHALIAS      "Public Domain"
  2.  
  3. NAME pathalias - mail routing tools
  4.  
  5. SYNOPSIS pathalias [-ivcDf] [-t link] [-l host] [-d link] [-g file]
  6.         [... files ...]
  7.  
  8. DESCRIPTION
  9.  
  10. Pathalias computes the shortest paths and corresponding routes from
  11. one host (computer system) to all other known, reachable hosts.
  12.  
  13. Pathalias reads host-to-host connectivity information on standard
  14. input or in the named files, and writes a list of host-route pairs
  15. on the standard output.
  16.  
  17. Here are the pathalias options:
  18.  
  19.     -i Ignore case:  map all host names to lower case.
  20.        By default, case is significant.
  21.  
  22.     -c Print costs: print the path cost before each host-route pair.
  23.  
  24.     -v Verbose: report some statistics on the standard error output.
  25.  
  26.     -D Terminal domains: see  domains section.
  27.  
  28.     -f First hop cost: the printed cost is the cost to the first
  29.        relay in a path, instead of the cost of the path itself;
  30.        implies (and overrides) the -c option.
  31.  
  32.     -g file         Dump the edges of the graph into the named file.
  33.  
  34.     -l host        Set local host name to host.  By default,
  35.             pathalias discovers the local host name in a
  36.             system-dependent way.
  37.  
  38.     -d arg        Declare a dead link, host, or network.  If
  39.             arg is of the form ``host-1!host-2,'' the link
  40.             from host-1 to host-2 is treated as an extremely
  41.             high cost (i.e. DEAD) link.  If arg is a single
  42.             host name, that host is treated as dead and is
  43.             used as a relay host of last resort on any path.
  44.             If arg is a network name, the network requires a
  45.             gateway. 
  46.  
  47.     -t arg        Trace input for link, host or network on the                    standard error output.     The form of arg is as
  48.             above.
  49.  
  50. Pathalias Input Format
  51.  
  52. A line beginning with white space continues the preceding line.
  53. Anything following `#' on an input line is ignored.
  54.  
  55. A list of host-to-host connections consists of a ``from'' host in column
  56. 1, followed by white space, followed by a comma-separated list of ``to''
  57. hosts, called links.  A link may be preceded or followed by a network
  58. character to use in the route. Valid network characters are `!' (default),
  59. `@', `:', and `%'.  A link (and network character, if present) may be
  60. followed by a ``cost'' enclosed in parentheses. Costs may be arbitrary
  61. arithmetic expressions involving numbers, parentheses, `+', `\-', `*',
  62. and `/'. Negative costs are prohibited. The following symbolic costs are
  63. recognized:
  64.     LOCAL    25    (local-area network connection)
  65.     DEDICATED    95    (high speed dedicated link)
  66.     DIRECT    200    (toll-free call)
  67.     DEMAND    300    (long-distance call)
  68.     HOURLY    500    (hourly poll)
  69.     EVENING    1800    (time restricted call)
  70.     DAILY    5000    (daily poll, also called \s-1POLLED\s0)
  71.     WEEKLY    30000    (irregular poll)
  72.  
  73. In addition, DEAD is a very large number (effectively infinite), HIGH and
  74. LOW are -5 and +5 respectively, for baud-rate or quality bonuses/penalties,
  75. and FAST is -80, for adjusting costs of links that use high-speed (9.6
  76. Kbaud or more) modems.  These symbolic costs represent an imperfect measure
  77. of bandwidth, monetary cost, and frequency of connections.  For most mail
  78. traffic, it is important to minimize the number of hosts in a route, thus,
  79. HOURLY * 24 is much larger than DAILY. If no cost is given, a default of
  80. 4000 is used.
  81.  
  82. For the most part, arithmetic expressions that mix symbolic constants
  83. other than HIGH, LOW, and FAST make no sense.  E.g., if a host calls a
  84. local neighbor whenever there is work, and additionally polls every evening,
  85. the cost is DIRECT, not DIRECT+EVENING.
  86.  
  87. Some examples:
  88.     down        princeton!(DEDICATED), tilt, %thrash(LOCAL)
  89.     princeton    topaz!(DEMAND+LOW)
  90.     topaz        @rutgers(LOCAL+1)
  91.  
  92. If a link is encountered more than once, the least-cost occurrence
  93. dictates the cost and network character. Links are treated as bidirectional
  94. but asymmetric: for each link declared in the input, a DEAD reverse link
  95. is assumed.
  96.  
  97. If the ``to'' host in a link is surrounded by angle brackets, the link
  98. is considered terminal, and further links beyond this one are heavily
  99. penalized. E.g., with input
  100.     seismo        <research>(10), research(100), ihnp4(10)
  101.     research    allegra(10)
  102.     ihnp4        allegra(50)
  103.  
  104. the path from seismo to research is direct, but the path from seismo
  105. to allegra uses ihnp4 as a relay, not research.
  106.  
  107. The set of names by which a host is known to its neighbors is called
  108. its aliases. Aliases are declared as follows:
  109.     name = alias, alias ...
  110.  
  111. The name used in the route to or through aliased hosts is the name by
  112. which the host is known to its predecessor in the route.
  113.  
  114. Fully connected networks, such as the ARPANET or a local-area network,
  115. are declared as follows:
  116.     net = {host, host, ...}
  117. The host-list may be preceded or followed by a routing character
  118. (`!' default), and may be followed by a cost (default 4000).  The network
  119. name is optional; if not given, pathalias makes one up.
  120.     etherhosts = {rahway, milan, joliet}!(LOCAL)
  121.     ringhosts = @{gimli, alida, almo}(DEDICATED)
  122.     = {etherhosts, ringhosts}(0)
  123.  
  124. The routing character used in a route to a network member is the one
  125. encountered when ``entering'' the network. See also the sections on
  126. gateways and domains.
  127.  
  128. Connection data may be given while hiding host names by declaring
  129.     private {host, host, ...}
  130. Pathalias will not generate routes for private hosts, but may produce
  131. routes through them. The scope of a private declaration extends from the
  132. declaration to the end of the input file in which it appears, or to a
  133. private declaration with an empty host list, whichever comes first.
  134. The latter scope rule offers a way to retain the semantics of private
  135. declarations when reading from the standard input.
  136.  
  137. Dead hosts, links, or networks may be presented in the input stream by declaring
  138.     dead {arg, ...}
  139. where arg has the same form as the argument to the -d option.
  140.  
  141. To force a specific cost for a link, delete all prior declarations with
  142.     delete {host-1!host-2}
  143. and declare the link as desired.
  144.  
  145. To delete a host and all its links, use
  146.     delete {host}
  147. Error diagnostics refer to the file in which the error was found.
  148.  
  149. To alter the file name, use
  150.     file {filename}
  151. Fine-tuning is possible by adjusting the weights of all links from a
  152. given host, as in
  153.     adjust {host-1, host-2(LOW), host-3(-1)}
  154. If no cost is given a default of 4000 is used.
  155.  
  156. Output Format
  157. A list of host-route pairs is written to the standard output,
  158. where route is a string appropriate for use with printf (3), e.g.,
  159.     rutgers    princeton!topaz!%s@rutgers
  160.  
  161. The ``%s'' in the route string should be replaced by the user name at
  162. the destination host. (This task is normally performed by a mailer.)
  163.  
  164. Except for domains, the name of a network is never used in routes.
  165. Thus, in the earlier example, the path from down to up would be
  166. ``up!%s,'' not ``princeton-ethernet!up!%s.''
  167.  
  168. Gateways
  169. A network is represented by a pseudo-host and a set of network members.
  170. Links from the members to the network have the weight given in the input,
  171. while the cost from the network to the members is zero. If a network is
  172. declared dead, the member-to-network links are marked dead, which
  173. effectively prohibits access to the network from its members.
  174.  
  175. However, if the input also shows an explicit link from any host to the
  176. network, then that host can be used as a gateway. (In particular, the
  177. gateway need not be a network member.)
  178.  
  179. E.g., if CSNET is declared dead and the input contains
  180.     CSNET = {...}
  181.     csnet-relay    CSNET
  182. then routes to CSNET hosts will use csnet-relay as a gateway.
  183.  
  184. Domains
  185. A network whose name begins with `.' is called a domain. Domains are
  186. presumed to require gateways, i.e., they are DEAD.  The route given by
  187. a path through a domain is similar to that for a network, but here the
  188. domain name is tacked onto the end of the next host.  Subdomains are
  189. permitted.
  190.  
  191. E.g.,
  192.     .harvard    EDU    # harvard is gateway to .EDU domain
  193.     .EDU        = {.BERKELEY, .UMICH}
  194.     .BERKELEY    = {ernie}
  195. yields
  196.     ernie    ...!harvard!ernie.BERKELEY.EDU!%s
  197.  
  198. Output is given for the nearest gateway to a domain, e.g., the example
  199. above gives
  200.     .EDU    ...!harvard!%s
  201.  
  202. Output is given for a subdomain if it has a different route than its
  203. pare